/* ===================

AX2E (AXESCON XACML 2.0 Engine) is the Java authorization engine, which implements OASIS XACML 2.0 standard.
Copyright (C) 2007 AXESCON LLC

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA


Contact: AXESCON LLC - info{at}axescon.com

 =================== */
package axescon.xacml.api;

import axescon.xacml.model.ctx.Attribute;
import axescon.xacml.model.ctx.XacmlCtx;
import axescon.xacml.model.policy.*;

/**
 * @author argyn
 * Date: Oct 19, 2005
 *         Responsibilities: evaluate various objects of Expression type of AXESCON XACML Model.
 * @see Expression
 */
public interface ExpressionEvaluator {

    /**
     * evaluates AttributeDEsignator against attributes array of request
     * @param x AttributeDesignator to be evaluated
     * @param attrs attributes array of Request object
     * @return result as AttributeValue objects array
     * @throws ExpressionEvalIndeterminateException
     * @throws XacmlException
     */
    AttributeValue[] eval(AttributeDesignator x, Attribute[] attrs)
            throws ExpressionEvalIndeterminateException, XacmlException;

    /**
     * evaluates array of Expressions against request object
     * @param exprs Expressions to be evaluated, each one will evaluate into one result element
     * @param ch context handler
     * @param req request
     * @return result as array of Liquid objects. each element corresponds to one Expression in arguments list
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    Liquid[] eval(Expression[] exprs, CtxHandler ch, XacmlCtx req) throws
            XacmlException, ExpressionEvalIndeterminateException;


    /**
     * evaluates AttributeDesignator against Environment attributes of request
     * @param x given AttributeDesignator
     * @param ch context handler
     * @param req request
     * @return array of attribute values
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    AttributeValue[] evalEnvironment(AttributeDesignator x, CtxHandler ch, XacmlCtx req)
            throws XacmlException, ExpressionEvalIndeterminateException;

    /**
     * evaluates AttributeDesignator against Resource attributes of request
     * @param x given AttributeDesignator
     * @param ch context handler
     * @param req request
     * @return array of attribute values
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    AttributeValue[] evalResource(AttributeDesignator x, CtxHandler ch, XacmlCtx req)
            throws ExpressionEvalIndeterminateException, XacmlException;

    /**
     * evaluates AttributeDesignator against Action attributes of request
     * @param x given AttributeDesignator
     * @param ch context handler
     * @param req request
     * @return array of attribute values
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    AttributeValue[] evalAction(AttributeDesignator x, CtxHandler ch, XacmlCtx req)
            throws ExpressionEvalIndeterminateException, XacmlException;

    /**
     * evaluates AttributeDesignator against Subject attributes of request
     * @param x given AttributeDesignator
     * @param ch context handler
     * @param req request
     * @return array of attribute values
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    AttributeValue[] evalSubject(SubjectAttributeDesignator x, CtxHandler ch, XacmlCtx req)
            throws ExpressionEvalIndeterminateException, XacmlException;

    /**
     * evaluates Apply against request
     * @param x given Apply object
     * @param ch context handler
     * @param req request
     * @return Liquid result
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    Liquid evalApply(Apply x, CtxHandler ch, XacmlCtx req)
            throws XacmlException, ExpressionEvalIndeterminateException;

    /**
     * gets AttributeSelectorEvaluator, which can be used to evaluate AttributeSelector expressions
     * @return AttributeSelectorEvaluator object
     */
    AttributeSelectorEvaluator getAttributeSelectorEvaluator();

    /**
     * sets AttributeSelectorEvaluator, which can be used to evaluate AttributeSelector expressions
     * @param attributeSelectorEvaluator
     */
    void setAttributeSelectorEvaluator(AttributeSelectorEvaluator attributeSelectorEvaluator);

    /**
     * get function factory, which can be used to evaluate expressions
     * @return function factory reference
     */
    FnFactory getFnFactory();
}
